/*
 *  libKara - Library for basic instant messaging functions
 *  Copyright (C) 2007 Markus Karnik
 *
 *  This program is free software; you can redistribute it and/or modify it 
 *  under the terms of the GNU General Public License as published by the
 *  Free Software Foundation; either version 3 of the License, 
 *  or (at your option) any later version.
 *
 *  This program is distributed in the hope that it will be useful, but
 *  WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
 *  or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 
 *  for more details.
 *
 *  You should have received a copy of the GNU General Public License along 
 *  with this program; if not, see <http://www.gnu.org/licenses/>.
 *  
 */

package de.karnik.libkara.pluginspecs;

import java.util.Vector;

import de.karnik.libkara.proto.ProtocolException;
import de.karnik.libkara.roster.ImContact;
import de.karnik.libkara.roster.ImMessage;

/**
 * The basic protocol definition class.
 * 
 * @author Markus Karnik - markus.karnik@my-design.org
 * @version 1.0
 * @since 1.0
 */
public abstract class BaseProtocol {
	
	/**
	 * XMPP available value.
	 */
	public static final int STATUS_AVAILABLE 	= 1;
	/**
	 * XMPP away value.
	 */
	public static final int STATUS_AWAY 		= 2;
	/**
	 * XMPP dnd value.
	 */
	public static final int STATUS_DND 			= 4;
	/**
	 * XMPP invisible value.
	 */
	public static final int STATUS_INVISIBLE 	= 8;
	/**
	 * XMPP offline value.
	 */
	public static final int STATUS_OFFLINE 		= 16;
	
	/**
	 * The account id.
	 */
	private String accountID = null;
	/**
	 * The protocol listeners.
	 */
	private Vector<ProtocolListener> protocolListeners = new Vector<ProtocolListener>( 1, 1 );
	
	/**
	 * Sets the account id.
	 * 
	 * @param accountID The account id to set.
	 */
	public void setAccountID( String accountID ) {
		this.accountID = accountID;
	}
	
	/**
	 * Returns the account id.
	 * 
	 * @return The account id.
	 */
	public String getAccountID() {
		return this.accountID;
	}
	
	/**
	 * Adds a protocol listener.
	 * 
	 * @param protocolListener The protocol listener to add.
	 */
	public void addProtocolListener( ProtocolListener protocolListener ) {
		this.protocolListeners.add( protocolListener );
	}
	/**
	 * Removes a protocol listener.
	 * 
	 * @param protocolListener The protocol listener to remove.
	 */
	public void removeProtocolListener( ProtocolListener protocolListener ) {
		this.protocolListeners.remove( protocolListener );
	}
	
	/**
	 * Returns all protocol listeners.
	 * 
	 * @return The protocol listeners.
	 */
	public Vector<ProtocolListener> getProtocolListeners() {
		return protocolListeners;
	}
	
	/**
	 * Connects the protocol.
	 * 
	 * @throws ProtocolException
	 */
	public abstract void proto_connect() throws ProtocolException;
	/**
	 * Disconnectes the protocol.
	 * 
	 * @throws ProtocolException
	 */
	public abstract void proto_disconnect() throws ProtocolException;
	/**
	 * Reconnect the protocol.
	 * 
	 * @throws ProtocolException
	 */
	public abstract void proto_reconnect() throws ProtocolException;
	
	/**
	 * Returns the connection indicator.
	 * 
	 * @return <b>true</b> if connected, <b>false</b> otherwise.
	 * @throws ProtocolException
	 */
	public abstract boolean proto_isConnected() throws ProtocolException;
	
	/**
	 * Configures the protocol.
	 * 
	 * @param protocolSettings The protocol settings.
	 * @throws ProtocolException
	 */
	public abstract void proto_configure( ProtocolSettings protocolSettings ) throws ProtocolException;
	/**
	 * Logs in the protocol with the settings values.
	 * 
	 * @throws ProtocolException
	 */
	public abstract void proto_login() throws ProtocolException;
	/**
	 * Logs off the protocol.
	 * 
	 * @throws ProtocolException
	 */
	public abstract void proto_logoff() throws ProtocolException;
	
	/**
	 * Refreshes the contact status of the given contact.
	 * 
	 * @param contact The contact to refresh.
	 * @throws ProtocolException
	 */
	public abstract void proto_refreshContactStatus( ImContact contact ) throws ProtocolException;
	
	/**
	 * Sets the current status for this protocol. Only the settings will be affected.
	 * 
	 * @param status The status to set.
	 * @throws ProtocolException
	 * 
	 * @see #STATUS_OFFLINE
	 * @see #STATUS_AVAILABLE
	 * @see #STATUS_AWAY
	 * @see #STATUS_DND
	 * @see #STATUS_INVISIBLE
	 */
	public abstract void proto_setStatus( int status ) throws ProtocolException;
	/**
	 * Sets the current status an sends a broadcast to the contactlist.
	 * 
	 * @param status The status to set.
	 * @throws ProtocolException
	 * 
	 * @see #STATUS_OFFLINE
	 * @see #STATUS_AVAILABLE
	 * @see #STATUS_AWAY
	 * @see #STATUS_DND
	 * @see #STATUS_INVISIBLE
	 */
	public abstract void proto_changeStatus( int status ) throws ProtocolException;
	/**
	 * Functions to send a message.
	 * 
	 * @param contact The contact to send the message to.
	 * @param message The message to send.
	 * @throws ProtocolException
	 */
	public abstract void proto_sendMessage( ImContact contact, ImMessage message ) throws ProtocolException;
	
	/**
	 * Returns the compatible major version.
	 * 
	 * @return The compatible major version.
	 */
	public abstract int proto_getCompatibleMajorVersion();
	/**
	 * Returns the compatible minor version.
	 * 
	 * @return The compatible minor version.
	 */
	public abstract int proto_getCompatibleMinorVersion();

}
